ParcelLabel API
Create Label(s) - International Outbound from NZ
Resource URL
UAT:
https://api.uat.nzpost.co.nz/parcellabel/v3/labelsProduction:
https://api.nzpost.co.nz/parcellabel/v3/labelsA unique consignment_id is returned once the details of the request are stored in the labeling database. One or multiple labels can be generated within a consignment Only a few [service codes][1] accept requests for multiple parcels.
The request is considered international if the pickup address is in New Zealand and the delivery address is not New Zealand.
Request Parameters
| Field Name | Description | Level of requirement | Notes on API validation rule | Notes on sending rules |
| format | Format of the label. | Not required | Value must be PDF or PNG. Default Value is PDF. | |
| notification_endpoint | Merchants Webhook URL to receive notification when the label has been generated. | Not required | ||
| delivery_choice_type | Additional service requested for the delivery. Value is a string and must be either 1 or 2. | Not required | ||
| sender_reference_1 | Sender's reference for the consignment. Will be printed on the label. | Recommended | ||
| sender_reference_2 | Sender's reference. Will not be printed on the label. | Not required | ||
| sender_details | An object containing the sender contact details. See Sender Details Object Parameters below. | Required | ||
| sender_details.name | Name of the sender. | Required | Both first name and surname should be included for customs clearance at destinations. | |
| sender_details.phone | Contact phone number of the sender. | Required if, otherwise highly recommended | NO SPACES, DIGITS and '+' ONLY | Required - If Express International services are used. |
| sender_details.email | Email address of the sender. | Recommended | ||
| sender_details.fax | Contact fax number of the sender. | Not required | ||
| sender_details.signatory | Name of the individual sending the parcel, this is used for Customs purposes. | Recommended | This is used for Customs purposes. | |
| sender_details.customs_code | Identification number assigned by overseas tax authorities. | Not required | For example: IOSS Number (EU),EORI number (UK and EU),ABN/ABR(Australia). | |
| receiver_details | An object containing the receiver contact details. See Receiver Details Object Parameters below. | Required | ||
| receiver_details.name | Name of the receiver. | Required | Both first name and surname should be included for customs clearance at destinations. | |
| receiver_details.phone | Contact phone number of the sender. | Required If or highly recommended | NO SPACES, DIGITS and '+' ONLY | Required - If Express International services are used. |
| receiver_details.email | Email address of the receiver. | Recommended | ||
| receiver_details.fax | Fax number of the person to receiver. | Not required | ||
| receiver_details.vat_number | The VAT or GST number of the receiver. | Required if | Maximum length of the field is 14 characters. | Required - If the parcels are sent: - to Brazil - to India and - Jordan via Express International services |
| receiver_details.registration_number | Registration number of the receiver required for Delivery Location Options. | Not required | ||
| pickup_address | An object containing the sender pickup address details. See Pickup Address parameters below: | Required | ||
| pickup_address.company_name | Company name of the pickup address. | Recommended if applicable | ||
| pickup_address.building_name | Building name of the pickup address. | Recommended if applicable | ||
| pickup_address.street_number | Street number of the pickup address. | Recommended if applicable | ||
| pickup_address.street | Street name of the pickup address. | Required | ||
| pickup_address.suburb | Suburb of the pickup address. | Required if | Some destination countries use suburb for delivery. | |
| pickup_address.city | City of the pickup address. | Required | ||
| pickup_address.state | Regional, provincial or county name of the pickup address. | Not required | ||
| pickup_address.locality_code | Country subdivision code identifier that the pickup address belongs to. | Not required | ||
| pickup_address.country_code | Two character country code of the pickup address. | Required | ||
| pickup_address.postcode | Postal or zip code of the pickup address. | Required If | Postcodes of some destinations are validated. | |
| delivery_address | An object containing the receiver delivery address details. See Receiver Address Object Parameters section. | Required | ||
| delivery_address.location_type | Type of the delivery requested for the item. Value must be from UPU code list 199. | Not required | ||
| delivery_address.building_name | Building name of the delivery address. | Recommended if applicable | ||
| delivery_address.company_name | Name of company that the parcel is being delivered to. | Recommended if applicable | ||
| delivery_address.street_number | Street number of the delivery address. | Required | ||
| delivery_address.street | Street name of the delivery address. | Required | ||
| delivery_address.suburb | Suburb of the delivery address | Required | If the destinations use suburb for delivery. | |
| delivery_address.city | City of the delivery address. | Required | ||
| delivery_address.state | State name of the delivery address. | Required If | If the destinations use state for delivery. | |
| delivery_address.locality_code | Country subdivision code identifier that the delivery address belongs to. | Recommended if applicable | ||
| delivery_address.country_code | Two character ISO country code of the delivery address. For domestic labels, this must be set to NZ. | Required | delivery_address.postcode | Postal or zip code of the delivery address. | Required If | Required - If the destination has a postcode system. |
| delivery_address.instructions | Delivery instructions. | Not required | ||
| return_address | An object containing the return address details. See Return Address parameters below: | Required | Mandatory for ETOE services. | |
| return_address.company_name | Company name of the return address. | Not required | ||
| return_address.building_name | Building name of the return address. | Not required | ||
| return_address.street_number | Street number of the return address. | Recommended | ||
| return_address.street | Street name of the return address. | Required | ||
| return_address.suburb | Suburb of the return address. | Recommended | ||
| return_address.city | City of the return address. | Required | ||
| return_address.state | Regional, provincial or county name of the return address. | Recommended | ||
| return_address.locality_code | Country subdivision code identifier that the return address belongs to. | Not required | ||
| return_address.country_code | Two character country code of the return address. | Required | Must be NZ for ETOE services. | |
| return_address.postcode | Postal or zip code of the return address. | Required | ||
| parcel_details | An object containing the label details for each label in the consignment. See Parcel Details Object Parameters section. | Required | ||
| parcel_details.service_code | Code to represent a delivery service. | Required | ||
| parcel_details.receiver_charging_arrangement | Duty and tax payment method as it applies to the item. Value must be DDP (Delivery Duty Paid) OR DDU (Delivery Duty Unpaid). | Not required | ||
| parcel_details.undeliverable_instructions | Instructions in case of non-delivery. | Required If | Value must be NONE, RETURN or DESTROY. | The undeliverable instructions vary for the services used. |
| parcel_details.indicia_number | Your indicia (PermitPost or DirectPost) number. | Required | The value “200003” can be used for label creation if there isn’t a PermitPost or DirectPost number has been assigned to your account. | |
| parcel_details.insurance_required | Whether additional cover is required for the parcel. Value must be either TRUE or FALSE. | Required If | Value must be either TRUE or FALSE. | The availability of Additional Cover varies by service and by the declared value of the parcel. |
| parcel_details.nature_of_transaction_code | Category of goods that appears on the CN23 form. Value depends on the nature of the items. | Required | Must be one of: 11=Sale of goods; 21=Returned Goods; 31=Gift; 32=Commercial Sample; 91=Documents; 991=Other | |
| parcel_details.postage_paid_amount | Monetary value of postage that sender has paid. | Required | Value must be greater than $0.00. | |
| parcel_details.additional_fee_amount | Monetary value of other fees that sender has paid. E.g. additional insurance. | Not required | ||
| parcel_details.insured_value_amount | Monetary value the parcels are covered for. | Not required | ||
| parcel_details.currency | Currency code for the parcel. | Required | ||
| parcel_details.dimensions | An object containing the dimension details of a parcel. See Parcel Details - Dimension Object Parameters section. | Required | ||
| parcel_details.dimensions.length_cm | Length of the parcel. | Required | ||
| parcel_details.dimensions.width_cm | Width of the parcel. | Required If | Required for rectangle parcels. | |
| parcel_details.dimensions.height_cm | Height of the parcel. | Required If | Required for rectangle parcels. | parparcel_details.dimensions.diameter_cm | Diameter of the parcel. | Required If | Required for tubes. |
| parcel_details.dangerous_goods | An object containing the hazard identification information of a parcel. See Parcel Details - Dangerous Goods Object Parameters section. Please refer to Dangerous Goods section for more information. | Required If | Required | |
| parcel_details.dangerous_goods.hazard_class | Classification of dangerous items in the parcel. Value must be from Hazard Identification Code. | Required If | http://www.ilo.org/legacy/english/protection /safework/cis/products/safetytm/tranann5.htm | Value must be from Hazard Identification Code and can only be 90. |
| parcel_details.dangerous_goods.type_code | United Nations Dangerous Goods identification code for dangerous items in the parcel. Value must be 4 digits. | Required If | Value can only either 3481 or 3091. | |
| parcel_details.parcel_contents | An array containing content details of a parcel. | Required If | ||
| parcel_details.parcel_contents.content_number | Number specifying an item in the parcel. | Required | Value must be an integer between 1 to 20 inclusive. | |
| parcel_details.parcel_contents.description | Description of the parcel contents. | Required | ||
| parcel_details.parcel_contents.harmonised_system_tariff | Harmonized System (HS) codes are commonly used throughout the import and export process for the classification of goods. The Harmonized System is a standardized numerical method of classifying traded products. | Required If | It is strongly recommended to remove all non-numeric characters, however use of ‘.’, or ‘ ‘ [space] is permitted between HS Tariff groupings. Examples: 1234567890 (preferred) 1234.56.78.90 (acceptable) 1234-56-78-90 (invalid characters) 1234.56.7 (invalid field length (7 numbers)). | List of destinations that require HS tariff codes to be provided can be found at nzpost.co.nz/ead. |
| parcel_details.parcel_contents.quantity | Quantity of units in the parcel. | Required | ||
| parcel_details.parcel_contents.weight_kg | Weight of each individual unit in the parcel (Unit: KG). | Required | ||
| parcel_details.parcel_contents.value | Dollar value of each individual unit in the parcel. | Required | ||
| parcel_details.parcel_contents.country_code | The 2-letter country code of the location in which the content piece was produced or manufactured. | Recommended if known | Value must be 2 characters. | |
| parcel_details.accompanying_documents | An object containing the accompanying document information of a parcel. See Parcel Details - Accompanying Documents Object Parameters section. | Not required | ||
| parcel_details.accompanying_documents.type | Code must be one of an allowed subset of codes. | Not required | Value must be one of LIC, 811 or 911 | |
| parcel_details.accompanying_documents.identifier | Value entered on the CN23 license box. | Not required |
Dangerous Goods - Lithium Battery
Below are the details and validations that are implemented when the customer is requesting labels for parcels containing devices that have lithium batteries either packed with, or contained with in it.
- Hazard Identification Details
| Field | Description | Supported values |
| parcel_details.dangerous_goods.hazard_class | Classification of dangerous items-Lithium Battery in the parcel. Value must be from Hazard Identification Code. | 90 |
| parcel_details.dangerous_goods.type_code | Dangerous Goods-Lithium Battery identification code for dangerous goods in the parcel. Value must be 4 digits. | 3091,3481 |
- Supported services and details
| Supported Label Provider(For Internal Use) | Supported service Codes | Supported destinations |
| GO_UPU_PROCESS | IECOT, IECOP, ICOU, ICOUE, IECOPRES, ICOU7, ICOURES, IECOP7 | Australia,Austria,Belgium,Canada,Chile,Hong Kong,Croatia,Denmark,El Salvador,Finland,France,French Polynesia,Georgia,Great Britain,Gibraltar,Hungary (Rep.),Japan,Korea (Rep.),Latvia,Lithuania,Malaysia,Monaco,Netherlands,Norway,Portugal,Saudi Arabia,Singapore,Slovenia,Spain,Sweden,Switzerland,Turkiye,United States of America |
| GO_DHL_PROCESS | IEXP,IEXPDTP,IEXPRES | All destinations enabled to these Services. |
| GO_AUS_PROCESS(CS_AUS) | ICOUSSAUN,ICOUSSAUT,ICOUSEAUS,ICOUSEAUN,ICOUSSAUS | All destinations enabled to these Services. |
- Validations
| Dangerous_Goods-Lithium Battery(LB) Validations | Validation results |
| Dangerous_Goods(DG) not provided in label request, then continue 'regular' label generation. | Label Generated. |
| Dangerous_Goods(DG) provided, but Label service is not Lithium Battery supported service label provider, then continue 'regular' label generation. | Label Generated. |
| Dangerous_Goods(DG) provided and Lithium Battery supported label provider, but service code is not Lithium Battery supported, then return an error message. | Error message: "The service is not available to send equipment including lithium batteries, visit nzpost.co.nz and search ECLB for more information. |
| Dangerous_Goods(DG) provided and service code is Lithium Battery supported service, but destination is not Lithium Battery supported destination, then return an error message. | Error message: “The last-mile delivery agent at the destination is not authorised to accept equipment including lithium batteries (ECLB), visit nzpost.co.nz and search ECLB for more information.“ |
| Dangerous_Goods(DG) provided and Lithium Battery supported service code and destination, but dangerous_goods/hazard_class is NOT 90, then return an error message. | Error message: "The only acceptable value of the field hazard_class is “90”, representing Class 9 - miscellaneous dangerous goods, which the lithium batteries are classified as." |
| Dangerous_Goods(DG) provided, Lithium Battery supported service code and destination, but dangerous_goods/type_code is NOT 3091 or 3481, then return an error message. | Error message: "The acceptable value of the field type_code is “3481” - Lithium ion batteries contained in equipment or “3091”- Lithium ion batteries packed with equipment." |
| Dangerous_Goods(DG) provided, Lithium Battery supported service code and destination, dangerous_goods/hazard_class is 90 and dangerous_goods/type_code is in (3091 or 3481), then continue label generation with ECLB indicator. | Label Generated with ECLB indicator. |
Sample Request
{
"carrier": "PARCELPOST",
"orientation": "LANDSCAPE",
"format": "PDF",
"sender_reference_1": "reference_1",
"sender_reference_2": "reference_2",
"paper_dimensions": {
"width_cm": 21.0,
"height_cm": 29.7,
"stationery_size": "A4"
},
"sender_details": {
"name": "Sender Name",
"phone": "+6490000001",
"email": "sender@example.co.nz",
"company_name": "Test Sender Company",
"site_code": 96306
},
"pickup_address": {
"company_name": "Test Pickup Address Company",
"building_name": "Test Pickup Address Building",
"unit_type": "Unit",
"unit_value": "2",
"floor": "Floor 5",
"street": "151 Victoria Street West",
"suburb": "Auckland Central",
"city": "Auckland",
"country_code": "NZ",
"postcode": "1010"
},
"receiver_details": {
"name": "Receiver Name",
"phone": "6490000002",
"email": "receiver@example.co.nz"
},
"delivery_address": {
"street": "20 George St",
"suburb": "",
"city": "Liverpool",
"state": "NSW",
"country_code": "AU",
"postcode": "2170"
},
"return_address": {
"company_name": "Test Return Address Company",
"building_name": "Test Return Address Building",
"unit_type": "Unit",
"unit_value": "2",
"floor": "Floor 5",
"street": "151 Victoria Street West",
"suburb": "Auckland Central",
"city": "Auckland",
"country_code": "NZ",
"postcode": "1010"
},
"parcel_details": [
{
"service_code": "TIEC",
"undeliverable_instructions": "RETURN",
"indicia_number": "200003",
"insurance_required": false,
"nature_of_transaction_code": "91",
"postage_paid_amount": 0.01,
"currency": "NZD",
"dangerous_goods": {
"hazard_class": "90",
"type_code": "3091"
},
"dimensions": {
"length_cm": 30,
"width_cm": 30,
"height_cm": 30,
"weight_kg": 1
},
"parcel_contents": [
{
"content_number": 1,
"description": "Package Desc",
"quantity": 1,
"weight_kg": 1,
"value": 1
}
]
}
]
}
Response Parameters
| Field Name | Description | Mandatory |
| consignment_id | Unique identifier for the consignment if the request is successful. | Yes |
| message_id | A unique ID for the API call | Yes |
| success | Returns true if request is successful. Returns false if request is not successful. | Yes |
Sample Response
